Skip to content

Add ouroboros-consensus:tracing sublibrary - #2244

Merged
jasagredo merged 38 commits into
mainfrom
js/tracing-instances
Sep 29, 2026
Merged

jasagredo merged 38 commits into
mainfrom
js/tracing-instances

Conversation

@jasagredo

@jasagredo jasagredo commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

Move the tracing instances from cardano-node to ouroboros-consensus.

@jasagredo
jasagredo force-pushed the js/tracing-instances branch 2 times, most recently from b003a0e to 7b0838e Compare August 27, 2026 13:32
@jasagredo
jasagredo force-pushed the js/tracing-instances branch from e9b2bd8 to 8f27e3f Compare September 3, 2026 15:21
Comment thread nix/haskell.nix
Comment thread tracing/test/Test/Consensus/Tracing/MetaTrace.hs Outdated
Comment thread tracing/test/Test/Consensus/Tracing/Golden.hs
Comment thread tracing/Ouroboros/Consensus/Tracing/Consensus.hs Outdated
Comment thread tracing/Ouroboros/Consensus/Tracing/Era/Shelley/Render.hs Outdated
Comment thread ouroboros-consensus.cabal
Comment thread tracing/Ouroboros/Consensus/Tracing/ChainDB.hs Outdated
@jasagredo
jasagredo force-pushed the js/tracing-instances branch 2 times, most recently from 332726c to b73febc Compare September 9, 2026 12:08
@jasagredo jasagredo mentioned this pull request Sep 16, 2026
7 of 12 tasks
@jasagredo
jasagredo changed the base branch from main to js/cardano-config-and-keys September 16, 2026 10:44
@jasagredo
jasagredo added this pull request to stack #2296 September 16, 2026 10:44
@jasagredo
jasagredo force-pushed the js/tracing-instances branch 2 times, most recently from 2a51544 to cf25039 Compare September 28, 2026 09:16
@jasagredo
jasagredo removed this pull request from stack #2296 September 28, 2026 09:16
@jasagredo
jasagredo changed the base branch from js/cardano-config-and-keys to main September 28, 2026 09:17
Introduce a new public sublibrary 'tracing' with instances for Consensus types,
moved from cardano-node.
Moving it from cardano-node/cardano-api.
Reimplement, off cardano-api, the Shelley-era JSON rendering helpers that the
era tracing instances need: bech32 stake/reward addresses (CIP-19, via the
bech32 package), hex script hashes, and an era-generic script-purpose renderer
built on cardano-ledger-api's AnyEraScript projections (replacing cardano-api's
per-era Alonzo/Conway plutus-purpose rendering and its ShelleyBasedEra/
AlonzoEraOnwards era witnesses). Output matches cardano-api's.
Move Cardano.Node.Tracing.Era.Byron to Ouroboros.Consensus.Tracing.Era.Byron;
inline the trivial textShow helper (its only cardano-api use) and drop the
imports the old -Wno-unused-imports hack was masking.
The list of traced types was hand-written and had drifted from Consensus.Tracers:
six top-level tracers were missing, all of them ones whose type carries a peer
or has no block parameter, which is why they were easy to overlook.

  TraceGDDEvent, Jumping.TraceEventCsj, Jumping.TraceEventDbf,
  BlockFetch.TraceFetchClientState, TraceDecisionEvent, KESAgentClientTrace

They bring 14 more undocumented namespaces into knownUndocumented, 13 of them
KESAgentClientTrace's -- an entire tracer whose messages carry no documentation
at all, and which nothing was asserting anything about until now.

The peer type is a stand-in: no MetaTrace method looks at it, so this uses ()
rather than pulling in the node's address types.
LedgerDB, ImmutableDB, VolatileDB, PerasCertDB and PerasVoteDB do not have
tracers of their own. ChainDbArgs.updateTracer derives each from the ChainDB
tracer, and ChainDB.TraceEvent's allNamespaces maps all of their namespaces in
under LedgerEvent, ImmDbEvent, VolatileDbEvent and so on -- cardano-node has no
tracer for any of them either.

Listing them alongside ChainDB.TraceEvent meant every one of their namespaces
was checked twice under two different names, and appeared twice in
knownUndocumented: once as ChunkValidation.InvalidChunkFile and again as
ImmDbEvent.ChunkValidation.InvalidChunkFile, once as
Flavor.V2.BackendTrace.LSM.LSMSnap and again as
LedgerEvent.Flavor.V2.BackendTrace.LSM.LSMSnap.

Keep ChainDB.TraceEvent, which reaches all of them, and drop the 17 duplicated
ratchet entries.
'maximumDef' was the only thing taken from it, in two severity
computations. 'foldr max' over the same list gives the same answer, and
the main library does not depend on cardano-prelude either, so this
keeps a public library out of the dependency tree entirely.
cardano-ledger-api does ship a COMPLETE pragma over the seven
AnyEra*Purpose synonyms, so the wildcard was not future-proofing: it was
reachable today, and a Dijkstra guarding redeemer rendered as
{"kind":"UnknownPlutusPurpose"} in the logs.

Match all seven and drop the wildcard, so that the next era is a compile
error here rather than a marker in an operator's logs. Guarding has no
cardano-api rendering to preserve, so its item renders directly (like
spending and rewarding) and its witness index name is ours.
'purposesByItem' only covered three of the six Conway purposes, leaving
certifying, voting and proposing unpinned -- and those are exactly the
{"item": ...}-wrapped ones the comment above warns about, so the ones
most likely to drift. 'renderTxIn' had no entry either.

Add them, plus the guarding purpose, which needs the Dijkstra era and so
also exercises the other AnyEraScript instance rather than only Conway's.
cardano-node removed the instances for
[TraceLabelPeer peer (FetchDecision [Point header])] under
IntersectMBO/cardano-node#6667: nothing emits that list, and its
Accept/Decline/EmptyPeersFetch namespaces were the stale ones the
configuration consistency check rejected. The MetaTrace instance for
FetchDecision goes with them; its metricsDocFor advertised a
connectedPeers metric that no asMetrics ever produced.

What remains is LogFormatting (FetchDecision [Point header]), which
TraceDecisionEvent's own rendering needs, matching cardano-node master.
The docstring claimed to catch a namespace left out of 'allNamespaces',
but every check iterates 'allNamespaces' itself and 'namespaceFor' is
never called, so that mistake -- and a typo appearing in both places --
still passes. Catching it needs trace values, which these types have no
'Arbitrary' or 'Enum' to produce, so narrow the wording instead.
'tracing/golden' sits outside the test component's hs-source-dirs, so
without an 'extraSrcFiles' entry haskell.nix pruned it out of the
component source, and without '--no-create' tasty-golden then created
the missing file and reported a pass. The Nix check was green without
comparing anything.

Key the golden directories by test name so that adding one is a single
line and cannot forget either half.
'tracing' is public API -- HasIssuer, ConvertTxId, and every log shape an
operator parses -- but it was not in the list the check walks, so a later
change to its .hs files would never ask for a fragment. Its path is the
directory itself, since that is its hs-source-dirs.
@jasagredo
jasagredo added this pull request to stack #2336 September 29, 2026 15:58
@jasagredo
jasagredo removed this pull request from stack #2336 September 29, 2026 15:59
@jasagredo
jasagredo added this pull request to stack #2337 September 29, 2026 16:00
@jasagredo
jasagredo merged commit 620a136 into main Sep 29, 2026
25 of 26 checks passed
@jasagredo
jasagredo deleted the js/tracing-instances branch September 29, 2026 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants